---
title: Client reference
summary: Complete reference for every public member of PdfAPI.Client.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-09-17
---

# Client reference

This page documents every public member of `IPdfClient` (9 members) plus the 2 additional public members declared only on the concrete `PdfClient` class (`IsPdfa`, `Track`) — 11 members in total. The two `Convert` overloads are distinct members mapping to different endpoints and are never collapsed.

---

## Convert from request

Converts a request-shaped document to the requested output format via the remote `PdfAPI`.

| Field | Value |
| --- | --- |
| **Signature** | `PdfResult Convert(ConvertRequest request)` |
| **Kind** | Remote |
| **HTTP verb** | POST |
| **Resolved URL** | `<url>/v1/convert` |
| **Transport member** | `PostJson<PdfResult>` |
| **Request DTO** | `PdfAPI.Core.ConvertRequest` |
| **Response DTO** | `PdfAPI.Core.PdfResult` |
| **Endpoint** | [`POST v1/convert`](../../apis/pdfapi/endpoints/convert-controller.md#post-v1%2Fconvert) |
| **Source** | `PdfAPI.Client\PdfClient.cs:44-49` |

### Convert from request URL composition

```csharp
var url = "convert";
```

| Segment | Bound from | Notes |
| --- | --- | --- |
| — | — | No path segments or query parameters; the entire request is carried in the JSON body |

### Convert from request Parameters

| Parameter | Type | Required | Default | Purpose |
| --- | --- | --- | --- | --- |
| `request` | `PdfAPI.Core.ConvertRequest` | Yes | — | Serialized as the JSON POST body |

### Convert from request Returns

`PostJson<PdfResult>` returns a result envelope; this member unwraps it with `.Results.FirstOrDefault()`. An empty `Results` collection silently yields `null` rather than an exception.

### Convert from request Exceptions

| Exception | Thrown by | Condition |
| --- | --- | --- |
| — | — | No exception handling in `PdfClient`; transport and deserialization failures propagate unwrapped from `JsonHttpClient` |

### Convert from request Notes
- No null-check on `request` before the call.
- A `Results` collection with no elements yields `null`, indistinguishable from a genuinely
  empty successful response — see [BR-CLI-004](business-rules.md#br-cli-004-empty-result-handling).

---

## Convert from file bytes

Converts a file-shaped document, supplied as raw bytes plus a file extension, to the requested output format via the remote `PdfAPI`.

| Field | Value |
| --- | --- |
| **Signature** | `PdfResult Convert(byte[] file, string fileExtension, PdfFormat format = PdfFormat.Pdf)` |
| **Kind** | Remote |
| **HTTP verb** | POST |
| **Resolved URL** | `<url>/v1/convert/{fileExtension}?format={format}` |
| **Transport member** | `PostJson<PdfResult>` |
| **Request DTO** | `byte[]` (JSON body); `fileExtension` in the path; `format` in the query string |
| **Response DTO** | `PdfAPI.Core.PdfResult` |
| **Endpoint** | [`POST v1/convert/{fileExtension}`](../../apis/pdfapi/endpoints/convert-controller.md#post-v1%2Fconvert%2F%7Bfileextension%7D) |
| **Source** | `PdfAPI.Client\PdfClient.cs:51-56` |

### Convert from file bytes URL composition

```csharp
var url = $"convert/{fileExtension.Trim('.')}?format={format}";
```

| Segment | Bound from | Notes |
| --- | --- | --- |
| `{fileExtension.Trim('.')}` | `fileExtension` | Leading and trailing `.` characters are stripped, so both `".docx"` and `"docx"` produce the same path segment |
| `format` (query) | `format` | Serialized via `ToString()` — the `PdfFormat` enum **name**, not its numeric value |

### Convert from file bytes Parameters

| Parameter | Type | Required | Default | Purpose |
| --- | --- | --- | --- | --- |
| `file` | `byte[]` | Yes | — | Serialized as the JSON POST body |
| `fileExtension` | `string` | Yes | — | Source file extension; dots trimmed before use in the path |
| `format` | `PdfFormat` | No | `PdfFormat.Pdf` | Requested output format, carried in the query string |

### Convert from file bytes Returns

`PostJson<PdfResult>` returns a result envelope; this member unwraps it with `.Results.FirstOrDefault()`, silently yielding `null` when `Results` is empty.

### Convert from file bytes Exceptions

| Exception | Thrown by | Condition |
| --- | --- | --- |
| `NullReferenceException` | `PdfClient` | `fileExtension` is `null` — `Trim('.')` is called without a null guard |
| — | `JsonHttpClient` | Transport and deserialization failures propagate unwrapped |

### Convert from file bytes Notes
- No null-check on `file` before the call.
- See [BR-CLI-002](business-rules.md#br-cli-002-file-extension-trimming) and [BR-CLI-003](business-rules.md#br-cli-003-default-output-format).

---

## Extract page range

Extracts the requested page ranges from a document, entirely in-process.

| Field | Value |
| --- | --- |
| **Signature** | `PdfResult Extract(DocumentRange range)` |
| **Kind** | Local |
| **HTTP verb** | — |
| **Resolved URL** | — |
| **Transport member** | — |
| **Request DTO** | `PdfAPI.Core.Extract.DocumentRange` (in-process argument) |
| **Response DTO** | `PdfAPI.Core.PdfResult` |
| **Endpoint** | — (local call to `PdfAPI.Core.PdfClientService.ExtractPages`) |
| **Source** | `PdfAPI.Client\PdfClient.cs:32` |

### Extract page range URL composition

Not applicable — this member issues no HTTP call.

### Extract page range Parameters

| Parameter | Type | Required | Default | Purpose |
| --- | --- | --- | --- | --- |
| `range` | `PdfAPI.Core.Extract.DocumentRange` | Yes | — | Source document and the page ranges to copy |

### Extract page range Returns

Returns the `PdfResult` produced by `PdfClientService.ExtractPages`, which copies the requested page ranges via `PdfCopy`, clamps ranges past the end of the document, treats a stop page of `-1` as "to the last page", honours `IsOriginal`, and supports descending ranges. `PdfProcessorType` is set to `iTextSharp`.

### Extract page range Exceptions

| Exception | Thrown by | Condition |
| --- | --- | --- |
| `PdfAPI.Core.PdfException` | `PdfClientService.ValidatePdf` | The source document's bytes are not a valid PDF |

### Extract page range Notes
- Executes entirely in the consumer's process; requires no API availability.
- See [BR-CLI-009](business-rules.md#br-cli-009-page-range-extraction-clamping).

---

## Check is pdf

Reports whether a byte array is a valid PDF, entirely in-process.

| Field | Value |
| --- | --- |
| **Signature** | `bool IsPdf(byte[] pdf)` |
| **Kind** | Local |
| **HTTP verb** | — |
| **Resolved URL** | — |
| **Transport member** | — |
| **Request DTO** | `byte[]` |
| **Response DTO** | `bool` |
| **Endpoint** | — (local call to `PdfAPI.Core.PdfClientService.IsPdf`) |
| **Source** | `PdfAPI.Client\PdfClient.cs:26` |

### Check is pdf URL composition

Not applicable — this member issues no HTTP call.

### Check is pdf Parameters

| Parameter | Type | Required | Default | Purpose |
| --- | --- | --- | --- | --- |
| `pdf` | `byte[]` | Yes | — | Bytes to test |

### Check is pdf Returns

Returns `false` for `null`; otherwise requires a length of at least 5 bytes, the `%PDF` magic bytes (`0x25 0x50 0x44 0x46`), and a `"%PDF-"` header prefix.

### Check is pdf Exceptions

| Exception | Thrown by | Condition |
| --- | --- | --- |
| — | — | Never throws; returns `false` for any input that is not a valid PDF, including `null` |

### Check is pdf Notes
- See [BR-CLI-006](business-rules.md#br-cli-006-valid-pdf-byte-array-check).

---

## Merge documents

Converts non-PDF inputs as needed and merges all documents into a single PDF via the remote `PdfAPI`.

| Field | Value |
| --- | --- |
| **Signature** | `PdfResult Merge(MergeRequest request)` |
| **Kind** | Remote |
| **HTTP verb** | POST |
| **Resolved URL** | `<url>/v1/merge` |
| **Transport member** | `PostJson<PdfResult>` |
| **Request DTO** | `PdfAPI.Core.MergeRequest` |
| **Response DTO** | `PdfAPI.Core.PdfResult` |
| **Endpoint** | [`POST v1/merge`](../../apis/pdfapi/endpoints/merge-controller.md#post-v1%2Fmerge) |
| **Source** | `PdfAPI.Client\PdfClient.cs:58-63` |

### Merge documents URL composition

```csharp
var url = "merge";
```

| Segment | Bound from | Notes |
| --- | --- | --- |
| — | — | No path segments or query parameters; the entire request is carried in the JSON body |

### Merge documents Parameters

| Parameter | Type | Required | Default | Purpose |
| --- | --- | --- | --- | --- |
| `request` | `PdfAPI.Core.MergeRequest` | Yes | — | Serialized as the JSON POST body |

### Merge documents Returns

`PostJson<PdfResult>` returns a result envelope; this member unwraps it with `.Results.FirstOrDefault()`, silently yielding `null` when `Results` is empty.

### Merge documents Exceptions

| Exception | Thrown by | Condition |
| --- | --- | --- |
| — | — | No exception handling in `PdfClient`; transport and deserialization failures propagate unwrapped from `JsonHttpClient` |

### Merge documents Notes
- No null-check on `request` before the call.
- See [BR-CLI-004](business-rules.md#br-cli-004-empty-result-handling).

---

## Count pages

Counts the pages in a PDF, entirely in-process.

| Field | Value |
| --- | --- |
| **Signature** | `int Pages(byte[] pdf)` |
| **Kind** | Local |
| **HTTP verb** | — |
| **Resolved URL** | — |
| **Transport member** | — |
| **Request DTO** | `byte[]` |
| **Response DTO** | `int` |
| **Endpoint** | — (local call to `PdfAPI.Core.PdfClientService.GetPageCount`) |
| **Source** | `PdfAPI.Client\PdfClient.cs:24` |

### Count pages URL composition

Not applicable — this member issues no HTTP call.

### Count pages Parameters

| Parameter | Type | Required | Default | Purpose |
| --- | --- | --- | --- | --- |
| `pdf` | `byte[]` | Yes | — | PDF bytes to inspect |

### Count pages Returns

Validates the bytes via `PdfClientService.ValidatePdf`, then UTF-8-decodes them and counts `/Type /Page[^s]` regex matches.

### Count pages Exceptions

| Exception | Thrown by | Condition |
| --- | --- | --- |
| `PdfAPI.Core.PdfException` | `PdfClientService.ValidatePdf` | `pdf` is not a valid PDF |

### Count pages Notes
- See [BR-CLI-007](business-rules.md#br-cli-007-invalid-pdf-exception).

---

## Read pdf version

Reads the PDF version from the document header, entirely in-process.

| Field | Value |
| --- | --- |
| **Signature** | `string Version(byte[] pdf)` |
| **Kind** | Local |
| **HTTP verb** | — |
| **Resolved URL** | — |
| **Transport member** | — |
| **Request DTO** | `byte[]` |
| **Response DTO** | `string` |
| **Endpoint** | — (local call to `PdfAPI.Core.PdfClientService.Version`) |
| **Source** | `PdfAPI.Client\PdfClient.cs:22` |

### Read pdf version URL composition

Not applicable — this member issues no HTTP call.

### Read pdf version Parameters

| Parameter | Type | Required | Default | Purpose |
| --- | --- | --- | --- | --- |
| `pdf` | `byte[]` | Yes | — | PDF bytes to inspect |

### Read pdf version Returns

Validates the bytes via `PdfClientService.ValidatePdf`, then regex-matches `%PDF-(?<version>\d+\.\d+)` against the ASCII-decoded header; returns `""` when no match is found.

### Read pdf version Exceptions

| Exception | Thrown by | Condition |
| --- | --- | --- |
| `PdfAPI.Core.PdfException` | `PdfClientService.ValidatePdf` | `pdf` is not a valid PDF |

### Read pdf version Notes
- See [BR-CLI-010](business-rules.md#br-cli-010-pdf-version-reporting).

---

## Flatten form fields

Flattens form fields in a PDF, entirely in-process.

| Field | Value |
| --- | --- |
| **Signature** | `byte[] Flatten(byte[] pdf)` |
| **Kind** | Local |
| **HTTP verb** | — |
| **Resolved URL** | — |
| **Transport member** | — |
| **Request DTO** | `byte[]` |
| **Response DTO** | `byte[]` |
| **Endpoint** | — (local call to `PdfAPI.Core.PdfClientService.Flatten`) |
| **Source** | `PdfAPI.Client\PdfClient.cs:30` |

### Flatten form fields URL composition

Not applicable — this member issues no HTTP call.

### Flatten form fields Parameters

| Parameter | Type | Required | Default | Purpose |
| --- | --- | --- | --- | --- |
| `pdf` | `byte[]` | Yes | — | PDF bytes to flatten |

### Flatten form fields Returns

Validates the bytes via `PdfClientService.ValidatePdf`; when `AcroForm` is non-null, re-writes the document through `PdfStamper { FormFlattening = true }`, otherwise returns the input bytes unchanged.

### Flatten form fields Exceptions

| Exception | Thrown by | Condition |
| --- | --- | --- |
| `PdfAPI.Core.PdfException` | `PdfClientService.ValidatePdf` | `pdf` is not a valid PDF |

### Flatten form fields Notes
- See [BR-CLI-008](business-rules.md#br-cli-008-flatten-with-no-acroform).

---

## Check has form fields

Detects whether a PDF has form fields, entirely in-process.

| Field | Value |
| --- | --- |
| **Signature** | `bool HasFormFields(byte[] pdf)` |
| **Kind** | Local |
| **HTTP verb** | — |
| **Resolved URL** | — |
| **Transport member** | — |
| **Request DTO** | `byte[]` |
| **Response DTO** | `bool` |
| **Endpoint** | — (local call to `PdfAPI.Core.PdfClientService.HasFormFields`) |
| **Source** | `PdfAPI.Client\PdfClient.cs:28` |

### Check has form fields URL composition

Not applicable — this member issues no HTTP call.

### Check has form fields Parameters

| Parameter | Type | Required | Default | Purpose |
| --- | --- | --- | --- | --- |
| `pdf` | `byte[]` | Yes | — | PDF bytes to inspect |

### Check has form fields Returns

Validates the bytes via `PdfClientService.ValidatePdf`, opens an `iTextSharp.text.pdf.PdfReader`, returns `false` when `AcroForm` is `null`, otherwise `AcroFields.Fields.Count > 0`.

### Check has form fields Exceptions

| Exception | Thrown by | Condition |
| --- | --- | --- |
| `PdfAPI.Core.PdfException` | `PdfClientService.ValidatePdf` | `pdf` is not a valid PDF |
| iTextSharp exceptions | `iTextSharp.text.pdf.PdfReader` | The bytes are malformed enough to fail parsing despite passing `ValidatePdf` |

### Check has form fields Notes
- None.

---

## Validate pdf a conformance

Validates PDF/A conformance via the remote `PdfAPI`. Declared only on the concrete `PdfClient` class — not on `IPdfClient` — so a caller holding only `IPdfClient` cannot reach this member.

| Field | Value |
| --- | --- |
| **Signature** | `bool IsPdfa(byte[] pdf)` |
| **Kind** | Remote |
| **HTTP verb** | POST |
| **Resolved URL** | `<url>/v1/info/validate/pdfa` |
| **Transport member** | `PostJson<bool>` |
| **Request DTO** | `byte[]` (JSON body) |
| **Response DTO** | `bool` |
| **Endpoint** | [`POST v1/info/validate/pdfa`](../../apis/pdfapi/endpoints/info-controller.md#post-v1%2Finfo%2Fvalidate%2Fpdfa) |
| **Source** | `PdfAPI.Client\PdfClient.cs:36-42` |

### Validate pdf a conformance URL composition

```csharp
var url = $"info/validate/pdfa";
```

| Segment | Bound from | Notes |
| --- | --- | --- |
| — | — | No path segments or query parameters; the bytes are carried in the JSON body |

### Validate pdf a conformance Parameters

| Parameter | Type | Required | Default | Purpose |
| --- | --- | --- | --- | --- |
| `pdf` | `byte[]` | Yes | — | Serialized as the JSON POST body |

### Validate pdf a conformance Returns

`PostJson<bool>` returns a result envelope; this member unwraps it with `.Results.FirstOrDefault()`, silently yielding `false` when `Results` is empty — indistinguishable from a genuine "not PDF/A" answer.

### Validate pdf a conformance Exceptions

| Exception | Thrown by | Condition |
| --- | --- | --- |
| — | — | No exception handling in `PdfClient`; transport and deserialization failures propagate unwrapped from `JsonHttpClient` |

### Validate pdf a conformance Notes
- See [BR-CLI-004](business-rules.md#br-cli-004-empty-result-handling).

---

## Track request status

Reads the current tracking status for a previously submitted conversion or merge request via the remote `PdfAPI`. Declared only on the concrete `PdfClient` class — not on `IPdfClient`.

| Field | Value |
| --- | --- |
| **Signature** | `PdfTrackingInfo Track(long trackingId)` |
| **Kind** | Remote |
| **HTTP verb** | GET |
| **Resolved URL** | `<url>/v1/info/track/{trackingId}` |
| **Transport member** | `GetResult<PdfTrackingInfo>` |
| **Request DTO** | `trackingId` in the path; no body |
| **Response DTO** | `PdfAPI.Core.PdfTrackingInfo`, returned directly — not unwrapped |
| **Endpoint** | [`GET v1/info/track/{trackingId}`](../../apis/pdfapi/endpoints/info-controller.md#get-v1%2Finfo%2Ftrack%2F%7Btrackingid%7D) |
| **Source** | `PdfAPI.Client\PdfClient.cs:65-69` |

### Track request status URL composition

```csharp
var url = $"info/track/{trackingId}";
```

| Segment | Bound from | Notes |
| --- | --- | --- |
| `{trackingId}` | `trackingId` | Placed directly in the path |

### Track request status Parameters

| Parameter | Type | Required | Default | Purpose |
| --- | --- | --- | --- | --- |
| `trackingId` | `long` | Yes | — | Identifier of the tracked conversion/merge request |

### Track request status Returns

`GetResult<PdfTrackingInfo>` returns the entity directly with no envelope unwrapping — unlike the four `PostJson<T>` call sites elsewhere on this client.

### Track request status Exceptions

| Exception | Thrown by | Condition |
| --- | --- | --- |
| — | — | No exception handling in `PdfClient`; transport and deserialization failures propagate unwrapped from `JsonHttpClient` |

### Track request status Notes
- Neither `retryIntervalMilliseconds` nor `retryCount` is passed, so the API's own server-side
  polling retry defaults (`retryIntervalMilliseconds=1000`, `retryCount=0`) apply — effectively a single, immediate status read. See [BR-CLI-005](business-rules.md#br-cli-005-tracking-status-polling-disabled).

---

## Coverage checklist

| Interface member | Documented section | Kind |
| --- | --- | --- |
| `PdfResult Convert(ConvertRequest request)` | [`Convert from request`](#convert-from-request) | Remote |
| `PdfResult Convert(byte[] file, string fileExtension, PdfFormat format = PdfFormat.Pdf)` | [`Convert from file bytes`](#convert-from-file-bytes) | Remote |
| `PdfResult Extract(DocumentRange range)` | [`Extract page range`](#extract-page-range) | Local |
| `bool IsPdf(byte[] pdf)` | [`Check is pdf`](#check-is-pdf) | Local |
| `PdfResult Merge(MergeRequest request)` | [`Merge documents`](#merge-documents) | Remote |
| `int Pages(byte[] pdf)` | [`Count pages`](#count-pages) | Local |
| `string Version(byte[] pdf)` | [`Read pdf version`](#read-pdf-version) | Local |
| `byte[] Flatten(byte[] pdf)` | [`Flatten form fields`](#flatten-form-fields) | Local |
| `bool HasFormFields(byte[] pdf)` | [`Check has form fields`](#check-has-form-fields) | Local |
| `bool IsPdfa(byte[] pdf)` *(concrete class only)* | [`Validate pdf a conformance`](#validate-pdf-a-conformance) | Remote |
| `PdfTrackingInfo Track(long trackingId)` *(concrete class only)* | [`Track request status`](#track-request-status) | Remote |

11 of 11 public members documented, each exactly once. 9 declared on `IPdfClient`; 2 (`IsPdfa`, `Track`) declared only on the concrete `PdfClient` class.

## Related documentation
- [Client index](index.md)
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Package](package.md)
- [Endpoint map](endpoint-map.md)
- [Consumption](consumption.md)
- [Contracts](contracts.md)
- [Dependencies](dependencies.md)
- [Business rules](business-rules.md)
- [Tech debt](tech-debt.md)

## Sources
- `PdfAPI.Client\PdfClient.cs`
- `PdfAPI.Client\IPdfClient.cs`
- `PdfAPI.Core\Services\PdfClientService.cs`